home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 626-637 / disk_629 / apig / apig31.lzh / old_release_info < prev    next >
Text File  |  1992-01-18  |  19KB  |  634 lines
  1.  
  2. ---------------------------------------------------------------------
  3. ---------------------------------------------------------------------
  4. APIG version 1.1  Released September 21, 1991
  5. ---------------------------------------------------------------------
  6. ---------------------------------------------------------------------
  7.  
  8.   Minor changes and minor bugs fixed.
  9.  
  10.     
  11.   * * * * *   Documentation Changes  * * * * *
  12.  
  13.   Too many to list (spelling and such), hopefully the doc file reads
  14.   better now.
  15.  
  16.  
  17.   ---------------
  18.   MAKEMENU      doc changed, all the parms were not listed
  19.   MAKEITEM      doc changed
  20.   MAKESUBITEM   doc changed
  21.  
  22.  
  23.   ---------------
  24.   SETSOFTSTYLE (added in version 0.5)  was not listed in the doc.
  25.  
  26.  
  27.   ---------------
  28.   TEXT
  29.   TEXTLENGTH
  30.  
  31.   The length of the text is computed for you only if the 'count' parm is 
  32.   less than zero, otherwise it uses the 'count' parm specified (including
  33.   zero).
  34.  
  35.  
  36.   ---------------
  37.   WINDOWINFO
  38.   
  39.   Code values have changed, see WINDOWINFO function docs.
  40.  
  41.  
  42.   ---------------
  43.   The Exec list functions INSERTNODE, REMHEAD, and REMTAIL were documented
  44.   wrong, (extraneous or missing parms), they worked per RKM.
  45.  
  46.  
  47.  
  48.   * * * * *   Changed Functions * * * * *
  49.  
  50.   ---------------
  51.   ENQUEUE
  52.  
  53.   Bug fix, this function was really doing a AddHead().
  54.  
  55.  
  56.   ---------------
  57.   LOADIFF
  58.   LOADIMAGE
  59.   MAKEBITMAP
  60.   MAKEITEXT
  61.   MAKEBOOLGADGET
  62.   MAKEBORDER
  63.   MAKEITEM
  64.   MAKEMENU
  65.   MAKEPROPGADGET
  66.   MAKERASTPORT
  67.   MAKEREQUESTER
  68.   MAKESTRGADGET
  69.   MAKESUBITEM
  70.   
  71.   These functions were changed to allow the use of an 'owner'.
  72.  
  73.  
  74.   ---------------
  75.   MAKEPROPGADGET
  76.   
  77.   Parms and their order have changed, see docs.
  78.  
  79.  
  80.   ---------------
  81.   MAKEMENU
  82.   MAKEITEM
  83.   MAKESUBITEM
  84.   
  85.   These functions were totally buggy, hopefully they are fixed now, the 
  86.   parms have changed a bit too.
  87.  
  88.  
  89.   ---------------
  90.   REQUEST/ENDREQUEST
  91.  
  92.   Mulitple requesters can now be put up with Request().
  93.   Note: AutoRequest still only allows one requester to be put up.
  94.  
  95.   Bug fix, ENDREQUEST would not end unless an Intuition Message was received.
  96.   eg.
  97.        /*  code like the following should now work  */
  98.  
  99.        x = Request( ... )     /* put up a requester */
  100.  
  101.        wait 5 sec             /* dont do anything   */
  102.  
  103.        x = Endrequest( ... )  /* end the requester  */
  104.        
  105.  
  106.  
  107.   ---------------
  108.   SETRGB4
  109.  
  110.   Parm change, last parm no longer required.
  111.  
  112.   eg.  x = SETRGB4(screen/window,pen,r,g,b,'S'/'W')
  113.  
  114.   The last parm indicated whether the first parm was a screen/window pointer
  115.   this is no longer neccessary.
  116.  
  117.   eg.  x = SETRGB4(screen/window,pen,r,g,b)
  118.  
  119.  
  120.   ---------------
  121.   SETVALUE
  122.  
  123.   Bug fix, this function did not work, possibly crashed, if 
  124.   the 'value' was null/zero when using the 'P'/'S' option.
  125.  
  126.   eg.  x = setvalue(mypointer,0,4,'p',0,0)
  127.                                       ^
  128.                                       +---- this being zero caused problems
  129.  
  130.  
  131.   ---------------
  132.   SETWINDOWTITLES 
  133.   SETWINDOWTITLE 
  134.  
  135.   Bug fix, title would disappear after setting it.
  136.  
  137.  
  138.   ---------------
  139.   WINDOWINFO
  140.   
  141.   Removed the redundant LeftEdge code, see WINDOWINFO function docs.
  142.  
  143.  
  144.  
  145.   * * * * *   New Functions * * * * *
  146.  
  147.   ---------------
  148.   FREEITEXT
  149.   FREEMENU
  150.   FREETHIS
  151.   
  152.   Frees memory allocated for specified structure. (See docs)
  153.  
  154.  
  155.   
  156.   ---------------
  157.   GETPREFS         Intuition Library
  158.   GETDEFPREFS      Intuition Library
  159.   SETPREFS         Intuition Library
  160.   GETSCREENDATA    Intuition Library
  161.  
  162.   ---------------
  163.   MAKEPOINTER
  164.   MAKESTRUCT
  165.  
  166.   These functions create an APIG pointer to a block of memory.
  167.  
  168.  
  169.   ---------------
  170.   SET_APIG_GLOBALS
  171.  
  172.   This function initializes many of the global constants used by/in the
  173.   various Intuition/Graphic data structures.
  174.  
  175.  
  176.  
  177.   * * * * *   General Notes & Things * * * * *
  178.  
  179.   ---------------
  180.   General
  181.  
  182.   *  Most structures can now 'own' another structure.
  183.   
  184.   *  Parms which are 'hex-strings' are now checked for odd addresses, if so
  185.      the parm is set to NULL, causing the function call to fail instead of
  186.      crashing with an illegal address error.
  187.  
  188.   *  Parms which are 'hex-strings' which point to low-mem (usually caused
  189.      by parms in the wrong order) are set to NULL, causing the function
  190.      call to fail. Low-mem means addresses in the first 1K.
  191.  
  192.   *  All functions are affected by the above changes since parms are 
  193.      converted before being passed to the 'glue' routines of the function
  194.      call. Functions which expect non-null pointers will simply return (fail).
  195.  
  196.   *  APIG now tries to determine if the parameters you pass are legal.
  197.      eg.  PRINTITEXT(rp,itptr,...) will not print the intuitext if 'itptr' 
  198.           does not point to an Intuitext structure. The call will fail,
  199.           returning zero.
  200.      
  201.   *  Because of the large number of string names used by SET_APIG_GLOBALS,
  202.      and parameter validation, the APIG library has grown considerably.
  203.  
  204.  
  205.   ---------------
  206.   ARexx quirks
  207.  
  208.   *  I suspect their is a bug in ARexx when passing 'hex-string' parms
  209.      to internal functions.  
  210.  
  211.      eg. If you have some generic function that processes a gadget lets say,
  212.          then code like the following may or may not work all the time.
  213.  
  214.  
  215.          /*  */
  216.  
  217.          mygad = makeboolgadget(w,...)
  218.  
  219.          x = processgadget(mygad)
  220.  
  221.          exit         
  222.  
  223.          processgadget:  procedure
  224.  
  225.          arg gadptr /* gadptr should be the 'hex-string' you passed  */
  226.                     /* well, sometimes it is and sometimes it is not */
  227.  
  228.          return something
  229.  
  230.          /*  */
  231.  
  232.     
  233.     I have not yet confirmed that this is a real ARexx bug with W. Hawes.
  234.     But if it is a real bug you can circumvent it with something like
  235.     this:
  236.  
  237.  
  238.          /*  */
  239.  
  240.          mygad = makeboolgadget(w,...)
  241.  
  242.          passgad = c2d(mygad)       /* this is gonna become a pain     */
  243.  
  244.          x = processgadget(passgad) /* would be nice if you could just */
  245.                                     /* pass it and not worry about it  */
  246.          exit         
  247.  
  248.          processgadget:  procedure
  249.  
  250.          arg passedarg
  251.          
  252.          gadptr = d2c(passedarg,4)  /* the '4' makes it 4byte 'hex-string' */
  253.  
  254.          then use gadptr
  255.  
  256.          return something
  257.  
  258.          /*  */
  259.  
  260.     Or you can 'expose' it, making it available to the procedure.
  261.     
  262.        eg.   processgadget: procedure expose mygad
  263.  
  264.  
  265.  
  266.     Or you can you use all global variables (ie. never use 'procedure')
  267.  
  268.  
  269.  
  270.  
  271. ---------------------------------------------------------------------
  272. ---------------------------------------------------------------------
  273. APIG version 0.5  Released June 14, 1991
  274. ---------------------------------------------------------------------
  275. ---------------------------------------------------------------------
  276.  
  277.    Font memory not fixed
  278.    
  279.    
  280.   * * * * *   Documentation Changes  * * * * *
  281.    
  282.  
  283.    -----------------
  284.    GETWINDOWRASTPORT
  285.    
  286.                   No change made to function. Documentaion did not
  287.                   show full name of function.  
  288.                   GETWINRASTPORT should have been GETWINDOWRASTPORT
  289.                   
  290.  
  291.    ---------------
  292.    SAVEIFFCLIP    No change made to function. Documentation changed - 
  293.                   Width of image must be expressed in bytes, NOT 
  294.                   pixels.
  295.  
  296.  
  297.    ---------------
  298.    WINDOWINFO     Codes 4 & 12 ARE redundant they both return the
  299.                   LeftEdge of the window, unchanged.
  300.                   
  301.                   Code 21 = GZZMouseX
  302.                   Code 22 = GZZMouseY
  303.                   The doc file had these reversed
  304.  
  305.  
  306.   * * * * *   Changed Functions * * * * *
  307.   
  308.   
  309.    ---------------
  310.    AUTOREQUEST    Bug fix, contrary to the documentation this function
  311.                   did return immediately, the result always being the
  312.                   value one.  The response to the requester was sent 
  313.                   to the window's port when the request ended.
  314.                   Changed to return when request ends, and the response
  315.                   to the requester is returned as a result of the
  316.                   function call.
  317.                   ie.  x = autorequest() returns 1 if 'positive' gadget
  318.                        selected, returns 0 if 'negative' gadget selected.
  319.                   
  320.    
  321.    ---------------
  322.    MAKEBORDER     changed to allow linking of border structures, also
  323.                   create 'auto' borders.
  324.                   new form of function call is now
  325.                   
  326.             MAKEBORDER(window,arrayptr,arraycnt,left,top,fp,bp,dm,borderptr)
  327.             
  328.              if the parm 'arrayptr' is 0, then a 'auto' border is built
  329.              using 'left' as the width of the border, and using 'top' as
  330.              the height of the border.  The parm 'arraycnt' determines
  331.              how 'thick' the border will be.
  332.  
  333.              the last parm 'borderptr' is a pointer to another border 
  334.              structure to which the new allocated border will be linked.
  335.              
  336.              borderptr - pointer to a border structure, code a 0 if not
  337.                          linking borders.
  338.              
  339.              All other parms are unchanged.
  340.             
  341.  
  342.    ---------------
  343.    MAKEREQUESTER  changed to allow specification of requester flags and
  344.                   to allow use of predrawn bitmap imagery
  345.                   new form of function call is now
  346.                   
  347.             MAKEREQUESTER(window,arrayptr,arraycnt,left,top,fp,bp,dm,border,
  348.                               flags,relLeft,relTop,bm)
  349.             
  350.              flags   - numeric, specifies POINTREL or PREDRAWN
  351.              relLeft - numeric, specifies left offset from mouse pointer            
  352.              relTop  - numeric, specifies top offset from mouse pointer
  353.                        (relLeft & relTop used with POINTREL)
  354.              bm      - pointer to bitmap, if using PREDRAWN requester
  355.                        imagery.
  356.                        
  357.              All other parms are unchanged.
  358.  
  359.    
  360.    ---------------
  361.    MODIFYPROP      Bug fix, function registers were loaded incorrectly,
  362.                    causing this function to hang.
  363.                    
  364.    ---------------
  365.    NEWMODIFYPROP   Bug fix, function registers were loaded incorrectly,
  366.                    causing this function to hang.
  367.                    
  368.    ---------------
  369.    WINDOWINFO     Bug fix, Code 11 = window Flag, was returning a short 
  370.                   when it should have been returning a long.
  371.                   now returns full 32bit long flag value                  
  372.                   
  373.                   
  374.                   
  375.   * * * * *   New Functions * * * * *
  376.   
  377.       ------------------------ 
  378.   <>  GADSELECTED( gadgetptr )
  379.   
  380.         This function returns TRUE/FALSE depending on the state of 
  381.         the gadget. 
  382.       
  383.         Inputs:
  384.  
  385.              gadgetptr  - pointer to a gadget
  386.           
  387.         Returns:        - returns 1 if the gadget state is SELECTED,
  388.                           otherwise returns 0.
  389.  
  390.  
  391.       ---------------------------- 
  392.   <>  GETGADPTR( window,gadgetid )
  393.  
  394.         This function searches the window's gadget list for a gadget with 
  395.         GadgetID equal to 'gadgetid' and returns a pointer to the gadget.
  396.       
  397.         Inputs:
  398.  
  399.             window     - pointer to window opened with OPENWINDOW().
  400.           
  401.             gadgetid   - numeric, gadgetid 
  402.           
  403.        Returns:        - pointer (ARexx hex-string) to gadget.
  404.  
  405.  
  406.  
  407.      ------------------------------ 
  408.   <> GETVALUE(ptr,offset,size,type)
  409.  
  410.    This function allows you to retreive the value of any parameter in
  411.    any data structure.
  412.  
  413.    ptr    - pointer, (ARexx hex string) to any data structure, ie. window
  414.             screen, bitmap, etc.
  415.  
  416.    offset - numeric, specifies the relative position, from the beginning
  417.             of the data structure, of data value you want to retrieve.
  418.             (see RKM or include '.i' files for offsets)
  419.  
  420.    size   - numeric, specifies the size of the data value you want to
  421.             retrieve.  This value must be either 1, 2, or 4.  Any other
  422.             value will cause the function to return a NULL ('0000 0000'x).
  423.             
  424.    type   - string, either a 'N', 'P' or 'S', this specifies the type
  425.             of data you are retrieving.
  426.  
  427.             'N' specifies that you want the value returned as a numeric.
  428.                 for sizes of 1 and 2 the returned value is always as a 
  429.                 numeric.
  430.  
  431.             If the size is 4 then you can also use (in addition to 'N')
  432.             the following:
  433.  
  434.             'P' specifies that you want the value returned as a pointer.
  435.                 (ie. ARexx hex string)
  436.  
  437.             'S' specifies that you want the value returned as a string.
  438.  
  439.                 VERY IMPORTANT NOTE !!! 
  440.                 When using 'P' or 'S',  'ptr' + 'offset' must result 
  441.                 in an address which contains a pointer to something.
  442.  
  443.  
  444.             eg.  You can retrieve the window title string with:
  445.             
  446.                  title = getvalue(windowpointer,32,4,'S')
  447.                  
  448.                  say "Your Window title is" title
  449.                  
  450.                  (the title string pointer is offset 32 from the beginning
  451.                   of the window structure)
  452.                   
  453.                  
  454.             eg.  To have the window title pointer returned as a pointer:
  455.                  
  456.                  titleptr = getvalue(win,32,4,'p')
  457.                  
  458.                  say "Window Title Pointer is " d2x(c2d(titleptr))
  459.                  
  460.                  
  461.             eg.  To return the contents of a string gadget:
  462.  
  463.                  specialstringinfo = getvalue(gadgetpointer,34,4,'P')
  464.                  gadcontents = getvalue(specialstringinfo,0,4,'S')      
  465.                  say "Your gad string is" gadcontents
  466.  
  467.  
  468.             eg.  Determining if a gadget is SELECTED:
  469.   
  470.                  if bittst(d2c(getvalue(gadpointer,12,2,'N')),7) = 1 then
  471.                     say "Gadget SELECTED"
  472.                  else
  473.                     say "Gadget NOT SELECTED"
  474.  
  475.                  getvalue(gadpointer,12,2,'N') returns the gadget Flags
  476.                  d2c() converts the result to form 'nnnn'x
  477.                  bittst() test bit 7, the gad select bit.
  478.                  
  479.  
  480.    returns -  the value you specified in the form specified.
  481.               defaults to returning numeric if type not 'N', 'P', or 'S'
  482.               returns NULL ('0000 0000'x) if size not 1, 2, or 4.
  483.               (their is no way to distinguish between returning a valid
  484.                null pointer ('P' type) and error in size)
  485.  
  486.  
  487.    ---------------------------------------- 
  488. <> SETVALUE(ptr,offset,size,type,value,len)
  489.  
  490.    This function allows you to set the value of any parameter in
  491.    any data structure.  Please be very certain about the parameters you
  492.    use in this function.
  493.  
  494.    ptr    - pointer, (ARexx hex string) to any data structure, ie. window
  495.             screen, bitmap, etc.
  496.  
  497.    offset - numeric, specifies the relative position, from the beginning
  498.             of the data structure, of the data value you want to set.
  499.             (see RKM or include '.i' files for offsets)
  500.  
  501.    size   - numeric, specifies the size of the data value you want to
  502.             set.  This value must be either 1, 2, or 4.  Any other
  503.             value will cause the function to return a NULL ('0000 0000'x).
  504.             
  505.    type   - string, either a 'N', 'P' or 'S', this specifies the form 
  506.             of the data 'value' you are passing.
  507.  
  508.             'N' specifies that the value is a numeric.
  509.                 for sizes of 1 and 2 the value is always taken (assumed)
  510.                 to be  a numeric.
  511.  
  512.             If the size is 4 then you can also use (in addition to 'N')
  513.             the following:
  514.  
  515.             'P' specifies that the value you are passing is a pointer.
  516.                 (ie. ARexx hex string)
  517.  
  518.             'S' specifies that the value you are passing is a string.
  519.  
  520.                 VERY IMPORTANT NOTE !!! 
  521.                 When using 'P' or 'S',  'ptr' + 'offset' must result 
  522.                 in an address which contains a pointer to something.
  523.  
  524.  
  525.    len    - numeric, used in conjuction with type 'S', this specifies
  526.             the maximum number of characters to be moved into the 
  527.             area pointed to by the pointer at 'ptr' + 'offset'.  
  528.             If you specify -1 the entire string will be copied into the 
  529.             area pointed to by the pointer.
  530.             
  531.             eg.  You can set the window title string with:
  532.             
  533.                  x = setvalue(windowpointer,32,4,'S',"MY NEW TITLE",-1)
  534.  
  535.                  This statement DIRECTLY modifies the contents of the
  536.                  buffer pointed to by the window title pointer.
  537.                  
  538.                  
  539.            The proper thing to do would be to modify where the window 
  540.            title pointer points.
  541.  
  542.            eg. 
  543.                mynewtitle = ALLOCMEM(length("MY NEW TITLE")+1,'0001 0000'x)
  544.  
  545.                call EXPORT(mynewtitle,"MY NEW TITLE")
  546.  
  547.                x = setvalue(windowpointer,32,4,'P',mynewtitle,0)
  548.                
  549.  
  550.    returns -  1 if successful, otherwise 0 
  551.  
  552.  
  553.       -------------------- 
  554. <>    WINTASKNAME(window)
  555.  
  556.       This function returns the name of the task managing the windows 
  557.       IDCMP port.  This is also the name of the public message port 
  558.       for the window.
  559.       
  560.       Inputs:
  561.       
  562.           window  - pointer to a window opened with OPENWINDOW().
  563.                  
  564.        
  565.       Returns:    - window task name string, ie. 'apig.task.N'
  566.                      
  567.  
  568.  
  569. ----  (Intuition/Graphic Library Functions Added) ----
  570.      
  571. <>   INTUITEXTLENGTH(itext)
  572.  
  573. <>   CLEARPOINTER(window)
  574.  
  575. <>   SETPOINTER(window,pointer,height,width,xoffset,yoffset)
  576.  
  577. <>   SETSOFTSTYLE(rp,style,enable)
  578.  
  579. <>   REMOVEGLIST(window,gadget,numgad)
  580.    
  581.    
  582.  
  583.  
  584. ---- (Exec Library Functions Added) ----
  585.      
  586.      All parameters for these functions must be 'hex-strings'
  587.      
  588. <>   ADDHEAD(list,node)
  589.  
  590. <>   ADDTAIL(list,node)
  591.  
  592. <>   ENQUEUE(list,node)
  593.  
  594. <>   INSERTNODE(list,node,listnode)
  595.      (note name differs, since ARexx has function with the name INSERT )
  596.  
  597. <>   NEWLIST(list)
  598.  
  599. <>   REMHEAD(list)
  600.  
  601. <>   REMOVE(node)
  602.  
  603. <>   REMTAIL(list)
  604.  
  605.  
  606. ---- APIG Library List related functions ----
  607.      
  608. <>   EMPTYLIST(list) - returns 1, if the list is empty, else returns 0
  609.  
  610. <>   LISTEMPTY(list) - same as EMPTYLIST()
  611.  
  612. <>   FIRSTNODE(list,node) - returns 1 if the node is first node in the list
  613.                             else returns 0.
  614.  
  615. <>   LASTNODE(list,node)  - returns 1 if the node is the last node in the list
  616.                             else returns 0.
  617.    
  618.  
  619.  
  620.  
  621. ---------------------------------------------------------------------
  622. ---------------------------------------------------------------------
  623. APIG version 0.1  Released May 18, 1991
  624. ---------------------------------------------------------------------
  625. ---------------------------------------------------------------------
  626.    
  627.  
  628.  Known bugs:
  629.    For some reason Font memory is not returned to the system memory
  630.    pool.
  631.  
  632.  
  633.  
  634.